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. The endpoint 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. 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 first reaches /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.

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 teams and memberships, your own items, 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 and ID 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.

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, and the effective visibility. It does not return internal derived values you cannot independently confirm; those are finalized only at submission. 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 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 whole /mcp endpoint. When it is off, the endpoint is not discoverable and returns 404.
• 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 overview 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, /mcp returns 404 rather than issuing 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.

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.