verae-mcp-timestamping-server/docs/api.md

Tool API

Server name: verae-timestamping.

stamp

Argument	Default	Meaning
sha256	required	64 hex characters
scope	local	local, shared, or global
cube_id	empty	Stored on the local receipt. Sent only as a local field on the global receipt object; the VeraeTime POST body is the digest
org_id	empty	Local idempotency key. Ignored by the global client

Returns { "receipts": [ Receipt ] }.

Receipt fields: receipt_id, hash, scope, cube_id, org_id, created_at, merkle, restamp_of.

verify

Argument	Default	Meaning
receipt_id	required	Local id or VeraeTime certificate / job id
want_scope	empty	global forces VeraeTime. A weaker scope fails closed when the stored scope ranks lower

Returns { "valid": bool, "error": string or null, "receipt": Receipt or null }.

Scope rank: local < shared < global.

hash_report

Argument	Default	Meaning
sha256	required	Digest to list
org_id	empty	Filter when set
want_scope	empty	Drop receipts below this rank

Returns { "receipts": [ ... ] }. want_scope=global queries VeraeTime GET /api/hash/{sha256} (Carfax). Empty want_scope merges the local file ledger with the central history.

login

Argument	Default	Meaning
username	required	VeraeTime account
password	required	VeraeTime password

POST /auth/login. Stores access_token, id_token, auth_token, expires_at, username, and password in the auth properties file (mode 0600) and replaces the in-memory JWT. Returns username, role, and expires_at. The JWT is not returned.

session

No arguments. GET /auth/validate with the stored JWT.

Returns valid, username, role, and expires_at.

signup

Argument	Default	Meaning
username	required	New account
password	required	New password

POST /auth/signup with no bearer token. The timestamping service creates the account with role user. Returns id, username, and role. Does not replace the JWT stored for stamp. A new account calls login to become the stored session. create_user remains the admin path and can set admin.

create_user

Argument	Default	Meaning
username	required	New account
password	required	New password
role	required	user or admin

POST /auth/users with the stored JWT. Refuses unless session reports role admin. Returns id, username, and role. Public registration is signup. create_user is how an admin sets a role.

A stored login is refreshed when stamp or verify runs and expires_at is missing or within 5 minutes, if username and password are in the auth file.

Environment

Name	Default
VERAE_GLOBAL_URL	https://api.veraetime.net
VERAE_GLOBAL_TOKEN	empty (then auth.properties)
VERAE_AUTH_PROPERTIES	~/.verae/auth.properties
VERAE_LEDGER_PATH	~/.verae/mcp-timestamp-local.json
VERAE_MCP_TRANSPORT	stdio
VERAE_MCP_HOST	127.0.0.1
VERAE_MCP_PORT	8000
VERAE_MCP_CORS	unset. 1 adds CORS for the sample page

Client config (stdio)

{
  "mcpServers": {
    "verae-timestamping": {
      "command": "uv",
      "args": ["run", "--directory", "/Users/marchon/research/modelcontextprotocol/verae-mcp-timestamping-server", "verae-mcp-timestamping-server"]
    }
  }
}