attest-mcp
The attest-mcp server provides tools to privately attest, verify, and manage proof-of-existence for digital works using SHA-256 fingerprinting, signed certificates, and Bitcoin anchoring — all without ever uploading your file bytes to any server.
Authorize: Initiate or continue a device-flow authentication session (or use an API key) to gain access to attestation services.
Attest a file: Compute a SHA-256 fingerprint of a local file (streamed locally, never uploaded) and submit it to the attestation service, which timestamps and cryptographically signs it (HMAC). Optional metadata (title, author, year, notes) can be bound to the signature.
Get a certificate PDF: Mint a fresh signed PDF certificate immediately after attestation, or recover a previously archived certificate using just the file's hash. Includes an RFC 3161 timestamp and Bitcoin anchor reference.
Verify a file: Hash a local file and compare it against a declared hash, attestation string, and HMAC signature from a certificate — confirming integrity and authenticity.
Verify a certificate: Validate the HMAC signature of an attestation and its declared metadata without needing the original file.
Check Bitcoin anchor: Determine if an OpenTimestamps proof exists for a specific SHA-256 hash and optionally download the
.otsproof file.Check service status: Get a real-time traffic-light health report on the attestation service components (worker, archive, signer, anchor).
Anchors file attestation timestamps on the Bitcoin blockchain via OpenTimestamps proofs, providing immutable proof of existence.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@attest-mcp attest this PDF and get the certificate"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
attest-mcp
Listed on the official MCP Registry as
io.github.SPAZIO-GENESI/attest-mcp.
MCP server and CLI for Spazio Genesi's attestation service — attest, verify, and check the existence of digital works from any MCP-capable AI agent (Claude Code, Claude Desktop, etc.) or straight from a terminal / CI pipeline.
Full privacy: file bytes never leave your device. The fingerprint (SHA-256) is computed locally, streamed from disk — only the hash and optional metadata are sent.
📖 English documentation: attestazione.spaziogenesi.org/en — site, developer docs, and tiers/terms are all available in English.
What it does
The attestation service timestamps a file's SHA-256 fingerprint, signs it (HMAC), and can produce a signed PDF certificate plus an OpenTimestamps proof anchored in Bitcoin. This server exposes that service as MCP tools, so an agent can attest and verify works on your behalf without a browser.
Related MCP server: AgentLedger
Why this, not just an OpenTimestamps wrapper
Several MCP servers can submit a hash to an OpenTimestamps calendar. As far as we know, this is the only one that hands back a complete proof of existence — a signed PDF certificate, a recognized RFC 3161 timestamp, and a Bitcoin anchor — for free, with the file's bytes never leaving the caller's machine. No account, no upload, no paid notarization chain. If you know of another MCP server with the same combination (full certificate + free + local hashing), we'd genuinely like to hear about it — open an issue.
Built for the European legal and regulatory context
Spazio Genesi is an Italian non-profit (ETS – Ente del Terzo Settore). The attestation service behind this package was designed with the EU regulatory environment in mind, not adapted to it afterwards:
GDPR-first, privacy by design: the file itself never reaches our servers — only its SHA-256 fingerprint (and any metadata you choose to declare) is sent.
EU data residency: certificates and proofs are archived on Cloudflare R2 under EU jurisdiction.
Recognized timestamping, no single point of trust: every certificate carries an RFC 3161 timestamp from an AATL-rooted authority (trusted by Adobe and most PDF readers) and an independent Bitcoin anchor via OpenTimestamps.
Honest about eIDAS: this is not (yet) an eIDAS qualified trust service — the signer identity is currently self-signed, and a qualified electronic seal is a planned but unimplemented upgrade. See the technical whitepaper for the full, unvarnished breakdown of what is and isn't guaranteed.
Full tiers and terms: attestazione.spaziogenesi.org/en/condizioni.
Install
Claude Desktop — one command, no manual JSON editing:
npx -y @spazio-genesi/attest-mcp-setupThis finds your claude_desktop_config.json (Windows/macOS/Linux), adds the
attest-mcp entry, and backs up the original file first. It refuses to touch
anything if the existing file isn't valid JSON — it never guesses. Restart
Claude Desktop afterwards. To remove it again: add --uninstall. To preview
without writing: add --dry-run.
Claude Code:
claude mcp add attest-mcp -- npx -y @spazio-genesi/attest-mcpManual / other clients — add this to your MCP client's config:
{
"mcpServers": {
"attest-mcp": {
"command": "npx",
"args": ["-y", "@spazio-genesi/attest-mcp"]
}
}
}Authentication
Two ways to authenticate, matching the underlying service:
API key (for partner integrations, issued manually by Spazio Genesi): set the
IMGAUTH_API_KEYenvironment variable.Device flow (for personal/agent use): call the
authorizetool with no arguments. It returns a URL — open it, approve with the human-verification widget, then callauthorizeagain with the returned code. The session token (24h, 20 attestations) is saved to~/.config/attest-mcp/credentials.json(permissions600where supported) and used automatically after that.
Either way, the credential only unlocks the anti-bot check on attestation — the server-side timestamp, cryptographic signature, and rate limits are unchanged.
Tools
Tool | What it does |
| Start or continue the device-flow authorization. |
| Hash a local file (streamed) and attest it. |
| Mint a fresh signed PDF, or recover an already-archived one, saved to disk. |
| Hash a local file and check it against a declared hash + signature. |
| Verify a certificate's signature without a local file. |
| Check/download the OpenTimestamps (Bitcoin) proof. |
| Traffic-light status of the attestation service. |
CLI (sg-attest)
Same package, no separate install. The CLI is a bin alongside the MCP server,
sharing the same hashing/API/config code — same full privacy (streamed local
hash, file bytes never sent), same credentials.
npx -y -p @spazio-genesi/attest-mcp sg-attest attest ./work.png
npx -y -p @spazio-genesi/attest-mcp sg-attest verify ./work.png --hash <sha256>(-p is required: sg-attest is a secondary bin of the package, and plain
npx -y @spazio-genesi/attest-mcp runs the MCP server instead.)
One advantage over the site: no 1 GB cap. The browser is limited by WebCrypto (which loads the whole file into memory); this CLI streams from disk on Node, so it can attest files of any size.
Command | What it does | Credential |
| Hash locally (streamed) → attest → print fingerprint, attestation, HMAC. Nothing is archived and no | Yes |
| Hash locally; with | No |
| Verifies a certificate's HMAC signature, no local file involved | No |
| Recovers an already-archived certificate | No |
| Checks/downloads the OpenTimestamps (Bitcoin) proof | No |
| Traffic-light status of the service | No |
| Device flow: prints a URL to approve, polls, saves the token | — |
| Version (from | — |
Every command accepts --json (emits one JSON object on stdout, for scripting)
and --quiet (reduces non-essential human-readable output). Errors go to
stderr; the CLI never prints a credential (API key or session token) to
stdout, stderr, or --json output — same discipline as the MCP server.
Exit codes (a stable contract, for CI/scripting):
Code | Meaning |
| Success / positive outcome |
| Operational error (network, auth, bad input) |
| Negative verification outcome (hash mismatch, invalid signature) |
Authentication is the same as the MCP server: IMGAUTH_API_KEY env var, or a
session token saved by sg-attest authorize (device flow). There is no
--key flag — a credential on the command line ends up in shell history; use
the env var (or a CI secret) instead.
A GitHub Action that uses this CLI to attest build artifacts in CI lives in a
companion repo: attest-action.
Standalone binaries (no Node required)
For a machine or CI runner without Node.js, download a pre-compiled sg-attest
executable from the Releases page —
same commands, same behavior, nothing to install.
OS | Architecture | File |
Linux | x64 |
|
Linux | arm64 |
|
macOS | Intel |
|
macOS | Apple Silicon |
|
Windows | x64 |
|
Windows | ARM64 |
|
Each release also includes SHA256SUMS.txt. Verify the download before running it:
sha256sum -c SHA256SUMS.txt --ignore-missing # Linux/macOS(Get-FileHash .\sg-attest-windows-x64.exe -Algorithm SHA256).Hash # compare by eye to SHA256SUMS.txt⚠️ The binaries are not code-signed: expect an "unknown publisher" warning from Windows SmartScreen or macOS Gatekeeper the first time you run one. The checksum above is the integrity guarantee in the meantime — the binary is built and published by GitHub Actions directly from this repo's source, nothing hand-uploaded.
Usage is identical to the npm-installed CLI, just call the file directly:
chmod +x ./sg-attest-linux-x64 # Linux/macOS only
./sg-attest-linux-x64 attest ./work.png --pdf cert.pdf
./sg-attest-linux-x64 statusnpx/npm remain the primary distribution channel (and what attest-action
uses in CI) — the binaries are an additional channel, not a replacement.
Build provenance (SLSA/in-toto)
The checksum above answers "is this file intact?" — it says nothing about
where the bytes came from. Every release since v0.4.2 also carries a
signed build provenance attestation
(actions/attest-build-provenance, job release in
release-binaries.yml): cryptographic
proof that the file was built by this repo's own workflow, from a specific
commit and tag, not hand-uploaded or swapped afterward.
The GitHub CLI can verify it, but gh attestation verify requires an
authenticated gh session even on this public repo (confirmed: it fails
with "please run gh auth login" without one) — a real gap if the point is a
check anyone can run with zero setup:
gh attestation verify sg-attest-linux-x64 --repo SPAZIO-GENESI/attest-mcpscripts/verify-provenance.mjs does the same
verification with no GitHub credentials at all — only the public
attestations REST endpoint (confirmed reachable unauthenticated, even on this
public repo) and the sigstore
library, which checks the signature against Sigstore's own public
infrastructure (Rekor, Fulcio, TUF — no account needed there either):
git clone https://github.com/SPAZIO-GENESI/attest-mcp
cd attest-mcp && npm install
node scripts/verify-provenance.mjs ./sg-attest-linux-x64 \
--repo SPAZIO-GENESI/attest-mcp --tag v0.4.2Exits 0 on success, 1 if the file doesn't match anything the workflow
actually built (e.g. a single altered byte makes the digest — and therefore
the lookup key itself — no longer match any attestation).
Configuration
Env var | Default | Purpose |
| — | API key credential, bypasses the device flow. |
|
| Override for local development ( |
|
| Override for the permanent-certificate-page base URL. |
Troubleshooting
If your client reports "Server disconnected", check its log first: this server
writes diagnostics to stderr, which MCP clients capture. On Claude Desktop the log
lives in %APPDATA%\Claude\logs\mcp-server-attest-mcp.log (Windows) or
~/Library/Logs/Claude/mcp-server-attest-mcp.log (macOS).
You should see one line per lifecycle event:
[attest-mcp 2026-07-21T11:14:12.948Z] v0.2.2 ready on stdio (node v22.22.2, pid 32316)
[attest-mcp 2026-07-21T11:14:12.965Z] exiting (code 0)exiting (code 0)— ordinary shutdown: the client closed stdin. After a laptop sleep or a client restart this is expected; just restart the client to reconnect.fatal: …followed byexiting (code 1)— a real crash, with the stack trace on the preceding line. Please open an issue with it.No
readyline at all — the process never started: check thatnodeis on PATH and at least v18 (node --version).
stdout carries the JSON-RPC protocol and is never used for logging.
Known limitation
The certificate PDF and its text are in Italian (Spazio Genesi is an Italian non-profit and the certificate is a legal-facing document). The MCP tool descriptions and this README are in English for an international audience.
Development
npm install
npm test # unit tests (hash vectors, CLI argument parsing)
IMGAUTH_BASE_URL=http://localhost:8787 npm start # MCP server against a local `wrangler dev`
IMGAUTH_BASE_URL=http://localhost:8787 node src/cli.js status # CLI against the sametest/cli-smoke.local.mjs is a local-only harness (not run by npm test) that
exercises every sg-attest command end-to-end against an isolated wrangler dev
imgauth instance — see the header comment in that file for the required env vars.
Security
Report vulnerabilities → /sicurezza/
(responsible disclosure policy, safe harbor for good-faith research) — this
repo has no security.txt of its own (npm package, no static assets), but
the policy covers the whole project.
Contributing
Bug reports and feature requests: open an issue.
Pull requests are welcome — keep them focused (one change per PR), make sure
npm test passes, and explain the "why" in the description, not just the
"what". Test policy: any PR that adds new functionality should add a test
for it under test/; npm run lint and npm test both run in CI on every
push and pull request. For anything that touches the attestation contract itself (hashing,
HMAC verification, the API surface), open an issue first: this client mirrors
a contract owned by imgauth, so
changes need to stay compatible with it.
License
MIT — see LICENSE. This is a client for the attestation service; the service itself (imgauth) is AGPL-3.0.
Available Tools
7 toolsattest_fileAttest a fileA
Compute the SHA-256 fingerprint of a local file (streamed, never sent anywhere) and attest it: the server timestamps it and returns a signed attestation. Requires a credential — run 'authorize' first, or set IMGAUTH_API_KEY. Optional declared metadata (titolo/autore/anno/note) is bound to the signature.
Inputs: path (required), anno, note, autore, +1 more.
authorizeAuthorize this agentA
Start or continue the device-flow authorization. Call with no arguments to begin: show the returned verification_url to the human and ask them to open it and approve. Then call again passing the same code, a few seconds apart, until status is 'approved' (token saved automatically) or 'expired' (start over). Grants 20 attestations for 24 hours.
Inputs: code.
check_anchorCheck the Bitcoin anchoring proofB
Check whether a fingerprint has an OpenTimestamps proof, optionally saving the .ots proof file to disk.
Inputs: hash (required), save_to.
get_certificate_pdfGet the certificate PDFA
Get the signed certificate PDF for an attested work, saving it to a local file. Pass attestation (the exact object returned by attest_file) right after attesting, to mint a freshly-signed PDF. Pass only hash to recover an already-archived certificate instead (no credential needed).
Inputs: hash (required), save_to, attestation.
service_statusCheck service statusA
Get the traffic-light status of the attestation service (worker, archive, signer, Bitcoin anchor).
Inputs: no named parameters.
verify_certificateVerify a certificate's signatureA
Verify the HMAC signature of a certificate's attestation (+ declared metadata, if any) without checking against any local file. Confirms authenticity and integrity of the declared data, not that a given file matches.
Inputs: hash (required), hmac (required), attestazione (required), anno, +3 more.
verify_fileVerify a file against a certificateB
Compute the SHA-256 of a local file and check it against a declared hash/attestation, plus verify the HMAC signature server-side (no file bytes are ever sent). Pass the fields as read from the certificate (hash, attestazione, hmac, and any declared titolo/autore/anno/note).
Inputs: path (required), anno, hash, hmac, +4 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool serves a distinct purpose: authorization, attestation, verification, certificate retrieval, anchor checking, and service status. No overlap or ambiguity.
Most tools follow verb_noun pattern (attest_file, check_anchor, get_certificate_pdf, verify_certificate, verify_file), but 'authorize' is a bare verb and 'service_status' is noun_noun, introducing minor inconsistency.
Seven tools cover the core workflow without being excessive. The scope is well-defined for an attestation service.
The set covers authorization, attestation, verification, certificate retrieval, anchor checking, and service status. Missing update/delete for attestations, but those are atypical for immutable attestations.
Maintenance
Related MCP Connectors
AI governance MCP server for EU AI Act compliance and jurisdiction verification
MCP server connecting AI agents to non-custodial staking data across 130+ networks.
Personal MCP server for humans who create. Proof of authorship, license control.
MCP server for the Z1N Protocol - on-chain identity for AI agents on Polygon
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP server for AI agent trust verification, enabling agents to verify identities, check trust scores, and build reputation across multiple blockchain and web platforms.1220 npm1MIT
- AlicenseAqualityDmaintenanceMCP server that stores AI agent reasoning traces permanently on 0G Storage, enabling immutable and verifiable decision logging.5MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for verifying and attesting SHA-256 fingerprints of digital works via Streamable HTTP, with zero-install and privacy-preserving design.MIT
- AlicenseAqualityBmaintenanceMCP server for GoCertius: certified evidence, dossiers, notifications and chats via AI agents.4175 npmMIT