Knowledge Base

Browse the concepts behind Truestamp. Follow the links between concepts, or search across everything.

MCP Server for LLM Agents

The authenticated Truestamp MCP server that connects an LLM agent (Claude Code, IDEs, Claude Desktop) over OAuth 2.1 with three code-mode tools, a mcp:read/mcp:write scope split, and a preview-then-submit confirm-before-write flow, alongside a public setup page on the same address.

Open resource

Overview

The Truestamp MCP server lets you connect an LLM agent (such as Claude Code, an IDE agent, or Claude Desktop) to your Truestamp account so the agent can read the ledger, look up your items, generate and verify proofs, and (with the right scope) create items on your behalf. It speaks the Model Context Protocol over an HTTP endpoint at /mcp. That address does double duty: opening www.truestamp.com/mcp in a browser shows the setup page for people, with the connect command and client configuration, while agents speak the protocol over the same address. The agent-facing side is a small “code mode” surface: rather than exposing dozens of narrow tools, it exposes three general tools and lets the agent compose the rest by writing short scripts against a curated, self-describing API. Agent access is OAuth 2.1 only, so there is no secret to paste by hand. To learn what Truestamp is and proves before you connect an agent, see what Truestamp is.

Connecting an agent with OAuth 2.1

The MCP endpoint is an OAuth 2.1 protected resource. It does NOT accept a Truestamp API key (those remain valid on the HTTP and console surfaces, just not here), and there is no header or token for you to copy. A compliant client performs the whole authorization handshake for you.

When a client sends its first protocol request to /mcp without a valid token, the server answers 401 with a WWW-Authenticate challenge that points at Truestamp’s authorization-server discovery metadata. From that single challenge the client finds the authorization server, registers itself automatically (dynamic client registration), runs a browser-based sign-in and consent step with PKCE, exchanges the result for a short-lived access token, and retries /mcp with that token. You approve the connection once in your browser; the client holds the token and renews it silently. The signed-in user carried by the token becomes the identity for every operation the agent performs, governed by the same authorization as the web app.

The server does not pin a single revision of the Model Context Protocol. It supports several and answers on the revision your client asks for, so clients tracking different revisions of the spec can both connect.

For Claude Code, adding the server needs no header and no key. The client runs the OAuth flow itself:

claude mcp add --transport http truestamp https://www.truestamp.com/mcp

Clients that can only send a static bearer header and cannot perform the OAuth flow cannot use /mcp; for those, use the Truestamp HTTP APIs with an API key instead.

Reconnecting after being idle

The access token is short-lived and normally renews on its own, so a running agent keeps working without asking you again. Some agents (Claude Code among them) may occasionally report that re-authorization is required after being idle for a long time, such as overnight. This is expected client behavior, not a Truestamp error. If it happens, just reconnect the server (re-run the add or connect step). Because the reconnect reuses the consent you already granted, you will not be asked to re-approve the same permissions.

The three code-mode tools

The endpoint publishes exactly three tools. An agent uses them in order.

  • Quickstart tool (quickstart) - the starting point. It returns what Truestamp is and proves, plus a short orientation to how the code-mode surface works, so a freshly connected agent knows what it can do. Call this first.
  • API docs tool (mcp_lua_docs) - the self-describing catalog. It lists every operation the agent can call from a script, with each operation’s inputs, returned fields, and description. The agent reads this before writing a script so it uses real operation names rather than guessing.
  • Script tool (mcp_lua_eval) - the workhorse. It runs a short Lua script that composes several catalog operations in a single round trip and returns the script’s result. This is how the agent lists items, reads the ledger, generates and verifies proofs, and creates items: by writing a small script instead of issuing many separate tool calls.

The set of operations a script may call is a curated allowlist. On the read side it covers the ledger and beacons, your own profile, your teams, memberships, and invitations, your own items and their lifecycle status (so an agent can pace its polling while a fresh item works its way toward verifiability), knowledge-base search, fetch, and link traversal (following the connections between concepts), your webhook endpoints and their delivery records, proof generate and verify, a proof’s download link and verification by reference, and hashing, canonicalization, ID, and server-clock utilities. On the write side it is a short list: creating an item, restoring a redacted item, creating a team, and creating, updating, or deleting a webhook endpoint. Deleting a webhook endpoint is a genuine destructive operation, so it too is available (guarded by mcp:write); the point is that writes are few and explicitly enumerated, not that none of them remove anything. Every call inside a script runs as your authenticated identity and is subject to the same Truestamp policies that govern the web app, so an agent can never reach an operation you could not perform yourself. What is deliberately absent from the surface entirely is account and user management, and any operation that destroys or redacts an item; items can be read, previewed, submitted and restored, but never deleted or redacted through this endpoint.

A script reads the same fields the other APIs show: an item’s witnesses are its witness_hashes, items and entropy observations carry no signature, a block carries its signature and signing_key_id, and asking a read for a field the resource does not have is refused as an unknown_field. The ledger resources are blockchain.block, blockchain.commitment and blockchain.epoch. A blockchain.commitment row is one kind of commitment at two levels, an item or observation into its block or a block into an epoch whose hash Truestamp wrote to Stellar or Bitcoin, told apart by its subject_kind and tree_kind, and it carries its inclusion_proof.

Choosing what a generated proof carries

Generating a proof reads and persists nothing, so mcp:read alone is enough for it. The generate operation returns the proof’s text, the signed document’s exact bytes, and every proof of an item carries every witness its fingerprint names. The entropy witnesses are values public sources published before the submission, and a verifier that reads them back draws the submitted-after edge of the submission window from them; the block witness places the item in Truestamp’s ledger and gives no edge. Its optional constructions argument says only how the proof carries the constructions text, in full (the default), as a reference to its published copy, or not at all; each is its own signed document, and the verdict never depends on it. See the proof bundle format for what each witness is and what a confirmed one establishes.

Because a script runs on the server, the sound way to answer “is this item verifiable” is to generate the proof and verify it in the same script, passing the text unchanged: the proof is never carried across the wire between the two steps. The verify operation reads the public chains unless its offline argument is set, under one deadline over the whole run that ends 3 seconds before the script’s 15-second time limit (a read not answered in time is reported as a skip, and the script still gets the report), and returns the verification report. A script that runs several verifications shares that one deadline among them. A proof the script asks for that Truestamp has not served before is checked against the public chains before it is signed, and those reads end by the same deadline: one not answered in time leaves the proof unserved for now, with the retryable evidence_unconfirmed code, and the script still gets that answer.

Proofs by reference

Two more operations spare an agent from copying a proof at all. The download link operation takes generate’s arguments and returns where to download the proof rather than its text: the address of the raw proof route (an item by its item code, with the item’s team in the address as tenant), which answers the exact file to a caller sending an API key, whichever of your teams holds the item, with the proof’s proof_hash and size. Give a person the link rather than a copy of the text. Asked for a view, it also returns the proof’s members as a table a script can read, for display only: verify takes a proof’s text, and refuses a table, so a view can never be handed back as a proof.

The verify by reference operation verifies the proof Truestamp serves of a subject, named by its id and type, and returns its report with the proof’s proof_hash and download address. It checks Truestamp’s own copy against the public chains; it is not an independent check of a file you hold. Given the text of your proof file as well, it reads that file strictly and compares it with the served proof of the file’s own constructions mode, and says whether the file is byte-identical (the report is then the report of your file), the same document in other formatting (a reformatted copy, its whole content the served one’s, whose bytes this run did not verify: verify the file itself), another document (another proof_hash, or the served proof with a changed or missing signature or an added member), or not a proof document it can read. Only a byte-identical file is ever called verified.

Reading a report in a script

Lua has no null, so a report member that is null, such as a submission-window edge that was not established or a check’s part, reads as nil in a script and is absent from what the script returns: read a member missing from a returned report as null. Lua also has one kind of table for objects and lists, so an empty object in a report comes back as an empty list. Everything else a script returns is the report as the verify operation gives it.

The mcp:read and mcp:write scope split

The endpoint distinguishes reading from writing through two OAuth scopes.

  • mcp:read is required to use the endpoint at all. Every request must carry it, and it is what the script tool needs to run. With mcp:read alone an agent can read the ledger, look up your items, and generate and verify proofs.
  • mcp:write is additionally required for any write performed inside a script, such as creating an item. It is enforced on each write operation, so a token that holds only mcp:read can read freely but a write attempt comes back as a clean “forbidden” result rather than an error or a crash.

You choose which scopes to grant when you approve the connection in your browser. Granting mcp:read only is the safe default for an agent that should observe but never change anything.

Confirm before writing: preview then submit

Creating an item is a two-step, confirm-before-write flow so a request phrased as “create an item” is never treated as approval of the exact values that will be committed. The catalog exposes a preview operation and a submit operation for this purpose.

Both operations take the claims as claims_json, the JSON text in a string, which is committed exactly as sent under the same claims rules as the other APIs: nothing is tidied, and a claim that breaks a rule is refused with its fix. The text may be up to 65,536 bytes, as on every surface. Write it in the script as a Lua long-bracket string, [==[ ... ]==], which Lua keeps exactly as written; in a quoted Lua string Lua rewrites each backslash escape first, so a JSON escape such as \u0041 or \n would silently change. Lua drops a newline right after the opening bracket, so start the JSON on the same line:

local claims = [==[{"name":"Quarterly report","hash_type":"sha256","hash":"dffd60..."}]==]
local p = items.item.preview({ input = { claims_json = claims } })

The preview operation computes what a create would produce without persisting anything: the resolved team, the claims as they would be stored including your complete data hash exactly as provided, claims_jcs (their exact canonical bytes) and claims_hash (computed over them, the values submit stores), the normalized tags, the effective visibility, and whether you have write access to that team. It is a faithful dry run rather than a separate reimplementation, so its verdict cannot drift from what submitting enforces. It does not return the item hash, which is finalized only at submission. A problem with the claims or the other arguments comes back as a normal result saying so, not as a tool error, so an agent can fix it and preview again: claims_castable is false, claims_reasons names each broken claims rule by its code, a message giving the fix, and a pointer to the member, and reasons gives the text of any other error, such as a bad tag. Claims that break no rule are returned beside such an error; claims that break one are left out. Submit refuses the same claims with one error per broken rule, carrying the same code and message. Write access is can_write, not claims_castable: preview checks no permission, write scope, monthly item limit or rate limit, so a preview with claims_castable true can still be followed by a submit refused for one of those. A typical agent flow is to call preview, show you the complete result (the full hash, never truncated, along with the name, team, visibility, and tags), wait for your explicit approval, and only then call submit (which requires mcp:write).

The submission timing guarantee applies here as everywhere in Truestamp: creating an item records its submission within a verifiable submission window, not a claim about when the underlying data was authored. To confirm that a resulting proof is valid, see verify a proof.

Restoring a redacted item

The restore operation, items.item.restore, returns a redacted item to committed with its original claims. It takes the item’s id (its UUIDv7 or item code) and claims_json, the claims as a JSON text of at most 65,536 bytes, written as a Lua long-bracket string like the claims of submit. Any formatting of the same claims restores, such as the claims_jcs the item had or a proof’s subject.claims written as JSON; claims whose claims hash is not the one the item kept are refused with “These claims do not match the original. Only the exact original claims, nonce included, can restore this item.” It requires mcp:write and the right to restore the item: its user owner, or an admin or owner of the team that owns it, and only a Truestamp system administrator undoes a compliance redaction. The tags removed with the claims are not restored. It returns the item’s id, item_code, state and claims_hash. A call without mcp:write, or with an empty claims_json, fails as a Lua error (its class is forbidden or invalid); any other refusal is a normal result with ok false and a code (invalid, forbidden or not_found). See the item lifecycle.

Feature flags that gate the server

The MCP surface is controlled by three feature flags, each enabled by default and each acting as a kill-switch a Truestamp administrator can flip.

  • The server flag is the master switch for the agent-facing endpoint. When it is off, protocol requests are not served and return 404, so no agent can connect. The setup page at /mcp is unaffected and stays up.
  • The code-mode flag governs the API docs and script tools specifically. When it is off, those two tools disappear from the agent’s tool list and calls to them are refused, while the quickstart tool and the rest of the endpoint stay up.
  • The write flag is narrower than its name suggests: it governs item creation (submit) specifically. When it is off, item creation is refused independent of whether a token holds mcp:write. It does not gate the other writes on the surface, so turning it off does not make the whole server read-only: a token that holds mcp:write can still restore a redacted item, create a team, and create, update, or delete a webhook endpoint. Those writes are governed by the mcp:write scope alone, not by this flag.

Because the endpoint is built on Truestamp’s OAuth authorization server, it also depends on that server being enabled: if the authorization server is turned off, protocol requests to /mcp return 404 rather than a discovery challenge that could not be followed.

Limitations

The endpoint operates Truestamp live through an agent; it is not the surface for generating standalone integration code against the HTTP APIs. An agent that needs to write a script or backend service against the REST/JSON:API or GraphQL endpoints uses those API-key surfaces instead, and can bootstrap from the public agent guide served at /llms-full.txt before it has a key or an MCP connection.

A request to the endpoint may be at most 1,052,672 bytes, room for a script’s text escaped into the request even when it is escaped as a quoted string in the script too, each time possibly doubling its size. A larger request is refused with 413 and the code request_too_large before any of it is parsed. A script may be at most 81,920 bytes, room for the largest claims text (65,536 bytes) in a long-bracket string and the call around it; a longer one is refused before it runs. That script limit is also how large a proof MCP can verify: a proof reaches verify only inside a script, so written into a long-bracket string it may be up to 81,920 bytes less the call around it. That holds every proof Truestamp serves, which is at most 65,536 bytes. A proof file reformatted to be larger, up to the 262,144 bytes verification reads, is verified over the JSON:API, GraphQL or raw verify route instead. A number written in the request itself (outside a string) may be at most 1,024 characters; a longer one gets the plain 400 Bad Request.

A request in which any JSON object has two members with the same name, at any depth, is refused with 400 Bad Request before any tool runs, because readers disagree on which of the two a repeated name means. Two names are the same when they are the same characters once JSON escapes are read. The error names the member, cut to its first 64 characters (member order in errors is not significant):

{"errors":{"detail":"A JSON object in the request has two members named \"script\".","member":"script"}}

A client that does not ask for JSON (no Accept header, */*, or text/html) gets an HTML error page with the same sentence instead. The JSON refusal, like the plain {"errors":{"detail":"Bad Request"}} a body that is not valid JSON gets, is served as application/json, as on every surface except the JSON:API, which serves it as application/vnd.api+json.

The server pins no team. There is no “current team” over MCP: reads of your items span all your teams automatically, and a write resolves the destination team server-side (from a supplied team, a named team, or your effective default team). An agent therefore sees and does exactly what you could in the web app without managing team context.

Citations

  1. RFC 6750: The OAuth 2.0 Bearer Token Usage. Backs the bearer-token authorization and the 401 WWW-Authenticate challenge.
  2. RFC 7591: OAuth 2.0 Dynamic Client Registration Protocol. Backs the client self-registration step of the connect flow.
  3. RFC 9728: OAuth 2.0 Protected Resource Metadata. Backs the protected-resource discovery metadata the 401 challenge points at.