three.ws Provenance — Claude Code MCP server: what it does and setup
Logs AI assistant actions to an append-only registry with EVM signatures. Useful when verifying delegation history or auditing third-party agents.
claude mcp add --env THREE_WS_BASE=<THREE_WS_BASE> --env THREE_WS_TIMEOUT_MS=<THREE_WS_TIMEOUT_MS> --env THREE_WS_TOKEN=<THREE_WS_TOKEN> --env THREE_WS_SIGNER_KEY=<THREE_WS_SIGNER_KEY> --transport stdio provenance-mcp -- npx -y @three-ws/provenance-mcpWhat three.ws Provenance does
The server connects an assistant to the three.ws ledger. Every recorded event is append-only, meaning existing logs cannot be overwritten or wiped. When an EVM private key is provided, the server signs the canonical payload using ERC-191 standards so authorship can be proven later.
Three tools handle the interaction. append_agent_action submits a new step to the ledger. Reading occurs via list_agent_actions with cursor pagination, while query_action extracts an entry by ID and runs ecrecover to identify the signer. Appending is non-idempotent: repeating the call writes an extra log entry.
Running the package requires Node.js 20 or higher alongside internet reach to https://three.ws. Requests fail without a valid THREE_WS_TOKEN because ledger access is restricted to the identity owner.
What it helps with
- record agent operations in an append-only verifiable registry
- verify cryptographic signatures on actions using
ecrecover - inspect an assistant's prior action feed using paginated cursors
- validate that third-party agent records were not modified
Example prompts for the agent
- Check action 10482 for agent
6a7d0f2c-1b3e-4a55-9c88-2d41b0f7e913usingquery_action. - Fetch the last 20 records for agent
6a7d0f2c-1b3e-4a55-9c88-2d41b0f7e913withlist_agent_actions. - Record a new
launchaction for agent6a7d0f2c-1b3e-4a55-9c88-2d41b0f7e913withappend_agent_action.
How to install three.ws Provenance
Platform CLI
claude mcp add --env THREE_WS_BASE=<THREE_WS_BASE> --env THREE_WS_TIMEOUT_MS=<THREE_WS_TIMEOUT_MS> --env THREE_WS_TOKEN=<THREE_WS_TOKEN> --env THREE_WS_SIGNER_KEY=<THREE_WS_SIGNER_KEY> --transport stdio provenance-mcp -- npx -y @three-ws/provenance-mcpReplace <…> with your own values
Platform CLI
codex mcp add provenance-mcp --env THREE_WS_BASE=<THREE_WS_BASE> --env THREE_WS_TIMEOUT_MS=<THREE_WS_TIMEOUT_MS> --env THREE_WS_TOKEN=<THREE_WS_TOKEN> --env THREE_WS_SIGNER_KEY=<THREE_WS_SIGNER_KEY> -- npx -y @three-ws/provenance-mcpReplace <…> with your own values
Config file
{
"mcpServers": {
"provenance-mcp": {
"command": "npx",
"args": [
"-y",
"@three-ws/provenance-mcp"
],
"env": {
"THREE_WS_BASE": "<THREE_WS_BASE>",
"THREE_WS_TIMEOUT_MS": "<THREE_WS_TIMEOUT_MS>",
"THREE_WS_TOKEN": "<THREE_WS_TOKEN>",
"THREE_WS_SIGNER_KEY": "<THREE_WS_SIGNER_KEY>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"provenance-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@three-ws/provenance-mcp"
],
"env": {
"THREE_WS_BASE": "<THREE_WS_BASE>",
"THREE_WS_TIMEOUT_MS": "<THREE_WS_TIMEOUT_MS>",
"THREE_WS_TOKEN": "<THREE_WS_TOKEN>",
"THREE_WS_SIGNER_KEY": "<THREE_WS_SIGNER_KEY>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e THREE_WS_BASE=<THREE_WS_BASE> -e THREE_WS_TIMEOUT_MS=<THREE_WS_TIMEOUT_MS> -e THREE_WS_TOKEN=<THREE_WS_TOKEN> -e THREE_WS_SIGNER_KEY=<THREE_WS_SIGNER_KEY> provenance-mcp npx -y @three-ws/provenance-mcpReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about three.ws Provenance
How do I install three.ws Provenance in Claude Code?
Run claude mcp add provenance-mcp -e THREE_WS_TOKEN=<THREE_WS_TOKEN> -e THREE_WS_SIGNER_KEY=<THREE_WS_SIGNER_KEY> -- npx -y @three-ws/provenance-mcp. Replace the placeholders with your three.ws token and EVM key.
What does three.ws Provenance do?
It provides tools to log assistant actions into an immutable ledger and verify them using ERC-191 signatures. This lets assistants build verifiable history trails and inspect other agents cryptographically.
What prerequisites are needed to run this MCP server?
You need Node.js 20 or newer, network access to https://three.ws, and a valid THREE_WS_TOKEN. To sign actions upon creation, provide THREE_WS_SIGNER_KEY as well.
