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.
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:readis required to use the endpoint at all. Every request must carry it, and it is what the script tool needs to run. Withmcp:readalone an agent can read the ledger, look up your items, and generate and verify proofs.mcp:writeis 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 onlymcp:readcan 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/mcpis 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 holdsmcp:writecan still restore a redacted item, create a team, and create, update, or delete a webhook endpoint. Those writes are governed by themcp:writescope 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
- RFC 6750: The OAuth 2.0 Bearer Token Usage. Backs the bearer-token authorization and the 401
WWW-Authenticatechallenge. - RFC 7591: OAuth 2.0 Dynamic Client Registration Protocol. Backs the client self-registration step of the connect flow.
- RFC 9728: OAuth 2.0 Protected Resource Metadata. Backs the protected-resource discovery metadata the 401 challenge points at.