three.ws Provenance

io.github.nirholasPublished by GitHub account nirholasv0.1.3Updated Oct 27, 2026

Append-only, signed, on-chain-verifiable agent action log — record and audit what agents did.

VerifiedSTDIODesktop onlySecurity & MonitoringAI & ML

Overview

AI-generated overview

Records and audits AI agent actions in an append-only, ERC-191-signed ledger on three.ws, letting an assistant append actions and verify another agent's…

What you can do
  • Read an agent's action trail newest-first with cursor pagination, each record signature-checked inline
  • Fetch a single action by id and recover its signer to prove authorship and integrity
  • Append a new action to the immutable ledger, optionally ERC-191-signed with an EVM key
  • Report verification results such as ok, signer_mismatch or unsigned for each record
When to use it
Use it when you need a tamper-evident history of what an agent did, or when you want to check that another agent's claimed trail is cryptographically signed by the address it names, for example before trusting a forked, purchased or delegated agent.
Requirements
Node.js 20 or newer, run locally via npx or npm install. Network access to three.ws or a custom THREE_WS_BASE. A required THREE_WS_TOKEN (three.ws API key or OAuth access token); the ledger is owner-scoped to agents that token owns. Optional THREE_WS_SIGNER_KEY and THREE_WS_TIMEOUT_MS.
Before you install
THREE_WS_TOKEN is a bearer credential for every call and should be treated like a password. THREE_WS_SIGNER_KEY is an EVM private key used to sign actions and should be treated like cash; a per-call signer_key argument can override it. Appends are permanent and not idempotent, so do not retry blindly. Action data is sent to the three.ws service.

Installation

In SourceWeft

  1. Open three.ws Provenance in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

[three.ws]

@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.

[npm] [license] [node] [MCP Registry] [three.ws]

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

bash
npm install @three-ws/provenance-mcp

Or run with npx (no install):

bash
npx @three-ws/provenance-mcp

Quick start

Claude Code, one line:

bash
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):

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:

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

Tools

ToolTypeWhat it does
list_agent_actionsread-onlyRead an agent's action trail, newest-first, cursor-paginated. Each record is signature-checked inline.
query_actionread-onlyFetch one action by id and recover its signer — proof the named agent authored that exact action, untampered.
append_agent_actionwriteERC-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:

  1. 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.
  2. 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).
  3. 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

jsonc
// 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": "…" }}
jsonc
// 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

VariableRequiredDefaultPurpose
THREE_WS_TOKENyes—Bearer token authenticating every call (API key or OAuth access token). Treat like a password.
THREE_WS_SIGNER_KEYno—0x EVM private key — when set, append_agent_action ERC-191-signs each action. Treat like cash.
THREE_WS_BASEnohttps://three.wsAPI base URL — override for self-hosting or a preview deployment.
THREE_WS_TIMEOUT_MSno20000Per-request timeout in milliseconds.

Links

Part of the three.ws SDK suite — 3D AI agents, on-chain identity, and agent payments.
Website · Changelog · GitHub

Source: packages/provenance-mcp/README.md at commit c8f2cde

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

2
  1. v0.1.3LatestOct 10, 2026
  2. v0.1.2Sep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts