@three-ws/provenance-mcp

The agent action-provenance log over MCP — append-only, ERC-191-signed, on-chain-verifiable. Record what an agent did, and audit another agent's trail, from any AI assistant.

license

A Model Context Protocol server for the three.ws agent trust layer. Every action an agent takes is written to an append-only ledger — optionally signed with the agent's EVM wallet (ERC-191), so its authorship is provable, not just claimed. This server lets one agent record its own actions and lets any agent read and cryptographically verify another agent's provenance trail.

Why it matters: a forked, purchased, or delegated agent is only trustworthy if its history is provable. provenance-mcp turns "the agent says it did X" into "the agent signed that it did X, and anyone can ecrecover the signer to confirm." The ledger is immutable — records are never edited or deleted.

Install

npm install @three-ws/provenance-mcp

Or run with npx (no install):

npx @three-ws/provenance-mcp

Quick start

Claude Code, one line:

claude mcp add provenance --env THREE_WS_TOKEN=sk_live_… -- npx -y @three-ws/provenance-mcp

Claude Desktop / Cursor (claude_desktop_config.json or mcp.json):

{
	"mcpServers": {
		"provenance": {
			"command": "npx",
			"args": ["-y", "@three-ws/provenance-mcp"],
			"env": {
				"THREE_WS_TOKEN": "sk_live_…",
				"THREE_WS_SIGNER_KEY": "0x…"
			}
		}
	}
}

Inspect the surface with the MCP Inspector:

THREE_WS_TOKEN=sk_live_… npx -y @modelcontextprotocol/inspector npx @three-ws/provenance-mcp

Tools

Tool	Type	What it does
`list_agent_actions`	read-only	Read an agent's action trail, newest-first, cursor-paginated. Each record is signature-checked inline.
`query_action`	read-only	Fetch one action by id and recover its signer — proof the named agent authored that exact action, untampered.
`append_agent_action`	write	ERC-191-sign a new action and append it to the immutable ledger. Never overwrites or deletes.

append_agent_action is the only write tool. It appends to an append-only ledger: every call records a new, permanent record (so it is not idempotent — don't retry blindly), and nothing is ever overwritten or removed (so it is not destructive).

Input parameters

list_agent_actions: agent_id (required, the agent identity's uuid), limit (1 to 200, default 50), cursor (numeric, from a previous next_cursor).

query_action: agent_id (required, the agent identity's uuid), id (required, numeric action id).

append_agent_action: agent_id (required, the agent identity's uuid), type (required, ≤64 chars), payload (object, optional), source_skill (optional), signer_key (optional 0x EVM key, overrides THREE_WS_SIGNER_KEY for this call).

How signing & verification work

When you append an action with a signer key configured, the server:

Builds a canonical form of the action — { v, agentId, type, payload, sourceSkill } with recursively sorted keys, so the same logical action always produces the same bytes.
SHA-256 digests it and frames the digest as threews:action:v1:<digest> (domain-separated, so an action signature can never be replayed as some other three.ws message).
ERC-191 personal_signs that string with the agent's EVM key and sends the resulting signature + signer_address alongside the action.

list_agent_actions and query_action reverse this offline: they recompute the digest from the stored record and ecrecover the signer. A verification.reason of ok means the signature recovers to the claimed address — cryptographic proof of authorship and integrity. signer_mismatch means the record does not verify (tampering, or a foreign signing scheme) and must not be trusted; unsigned means no signature was attached.

This is the same primitive three.ws uses server-side for its Portable & Verifiable Brain — verification needs nothing but the public record and the agent's address.

Example

// append_agent_action
> { "agent_id": "6a7d0f2c-1b3e-4a55-9c88-2d41b0f7e913", "type": "launch", "payload": { "mint": "FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump", "name": "$THREE" }, "source_skill": "pump-launch" }
{
  "ok": true,
  "action": {
    "id": "10482",
    "agent_id": "6a7d0f2c-1b3e-4a55-9c88-2d41b0f7e913",
    "type": "launch",
    "payload": { "mint": "FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump", "name": "$THREE" },
    "source_skill": "pump-launch",
    "signature": "0x…",
    "signer_address": "0xAbC…",
    "created_at": "2026-06-24T18:20:00.000Z"
  },
  "signing": { "signed": true, "signer_address": "0xAbC…", "digest": "…" }
}

// query_action  →  verify it independently
> { "agent_id": "6a7d0f2c-1b3e-4a55-9c88-2d41b0f7e913", "id": "10482" }
{
  "ok": true,
  "action": { "id": "10482", "type": "launch", "signature": "0x…", "signer_address": "0xAbC…", /* … */ },
  "verification": { "signed": true, "valid": true, "reason": "ok", "recovered": "0xAbC…", "digest": "…" }
}

Requirements

Node.js >= 20.
Network access to https://three.ws (or your own THREE_WS_BASE).
A THREE_WS_TOKEN — a three.ws API key (sk_live_…) or OAuth access token. The ledger authenticates every call and is owner-scoped: you can read and append actions only for agents your token owns.

Environment variables

Variable	Required	Default	Purpose
`THREE_WS_TOKEN`	yes	—	Bearer token authenticating every call (API key or OAuth access token). Treat like a password.
`THREE_WS_SIGNER_KEY`	no	—	0x EVM private key — when set, `append_agent_action` ERC-191-signs each action. Treat like cash.
`THREE_WS_BASE`	no	`https://three.ws`	API base URL — override for self-hosting or a preview deployment.
`THREE_WS_TIMEOUT_MS`	no	`20000`	Per-request timeout in milliseconds.

Part of three.ws

three.ws is a platform for 3D AI agents with Solana wallets: avatars, a skill marketplace, x402 payments and more than seventy MCP servers. @three-ws/provenance-mcp is one package from it.

Documentation site: https://nirholas.github.io/provenance-mcp/
npm: https://www.npmjs.com/package/@three-ws/provenance-mcp
Canonical source: https://github.com/nirholas/three.ws (this repository is a generated mirror of packages/provenance-mcp)
Agent-readable summary: llms.txt and AGENTS.md
Issues and ideas: https://github.com/nirholas/provenance-mcp/issues

provenance-mcp