Knowledge Base

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, and hashing, canonicalization, ID, and server-clock utilities. On the write side it is a short list: creating an 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, and submitted, but never deleted or redacted through this endpoint.

Choosing what a generated proof carries

Generating a proof reads and persists nothing, so mcp:read alone is enough for it. The generate operation takes an optional list of witnesses: the public records that existed before a submission and that the subject’s fingerprint commits to, which establish the submitted-after edge of the submission window. Leave the list out and the bundle carries every witness the subject captured, so the file stands alone; name a subset (say the head block and the NIST beacon pulse) for a smaller bundle. A name the server does not recognize is refused, and asking for a witness the subject never captured simply leaves it out. The choice never changes a hash or the signature, so a smaller bundle verifies exactly like a complete one. 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: the bundle is never carried across the wire between the two steps.

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.

The preview operation computes what a create would produce without persisting anything: the resolved team, the cast claims including your complete data hash exactly as provided, 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 internal derived values you cannot independently confirm; those are finalized only at submission. Claims that would be rejected come back as a normal result saying so and naming each offending field and rule, not as a tool error, so an agent can fix them and preview again. 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.

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 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. That leaves room for a proof of up to 256 KB (262,144 bytes) pasted into a script, which is escaped twice on the way, once as a quoted string in the script and again inside the request, 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.

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.