@provenonce/mcp

@provenonce/mcp

Provenonce Skill — Give any AI agent cryptographic identity in under 60 seconds.

Add this skill to your agent and it gets:

• A permanent cryptographic hash (identity)
• A SIGIL (verified identity class + tier)
• A signed Passport (verifiable offline by any third party)
• Heartbeat (continuous liveness proof)
• Beats proofs (evidence of computational work)
• Lineage (full ancestry chain)

Quick Start

Claude Desktop / Claude Code

Add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "provenonce": {
      "command": "npx",
      "args": ["-y", "@provenonce/mcp"]
    }
  }
}

That's it. On first use, your agent calls provenonce_register and gets a permanent identity.

With pre-existing credentials

{
  "mcpServers": {
    "provenonce": {
      "command": "npx",
      "args": ["-y", "@provenonce/mcp"],
      "env": {
        "PROVENONCE_API_KEY": "pvn_...",
        "PROVENONCE_AGENT_HASH": "0x..."
      }
    }
  }
}

As a skill developer (earn rev share)

If you're a developer embedding this skill in your framework, include your partner ref token:

{
  "env": {
    "PROVENONCE_SKILL_REF": "your16hextoken"
  }
}

You earn 30% of every SIGIL purchased by agents you deploy. Register at POST /api/v1/skill/register.

The 11 Tools

Tool	What it does	Auth needed
provenonce_register	Auto-register agent, get hash + API key	None
provenonce_status	Full current state (SIGIL, balance, hints)	Yes
provenonce_purchase_sigil	Buy SIGIL, unlock heartbeat + passport	Yes + SOL tx
provenonce_heartbeat	Submit liveness proof	Yes + SOL tx
provenonce_batch_heartbeat	Heartbeat multiple children in one call	Yes + SOL tx
provenonce_get_passport	Get signed identity document	Yes
provenonce_beats_proof	Compute work proof, get receipt (for spawn/resync)	None
provenonce_submit_beats	Compute VDF beats and credit lifetime beat count	Yes
provenonce_verify_agent	Check another agent's identity	None
provenonce_spawn	Spawn a child agent	Yes
provenonce_get_lineage	Get full ancestry chain	None

Usage Examples

Example 1: Register and check status

User prompt: "Register with Provenonce and show me my identity."

Expected behavior:

• Agent calls provenonce_register with an optional name
• Receives a permanent cryptographic hash (e.g. 0xabcd...) and API key
• Credentials are saved to ~/.provenonce/config.json
• Agent calls provenonce_status to display identity, balance, and next steps
• Status response includes a _hint suggesting the agent purchase a SIGIL

Example 2: Verify another agent before trusting it

User prompt: "Check if agent 0xf7dad8f4...b6fd is legitimate."

Expected behavior:

• Agent calls provenonce_verify_agent with the target hash
• Returns the agent's SIGIL, identity class, tier, registration date, and liveness score
• Agent reports whether the target has an active SIGIL and recent heartbeats
• No authentication needed — this is a public verification endpoint

Example 3: Full lifecycle — SIGIL, heartbeat, and passport

User prompt: "Get me a SIGIL, send a heartbeat, and export my passport."

Expected behavior:

• Agent calls provenonce_purchase_sigil without payment_tx to get fee instructions (amount in SOL + ops wallet address)
• User sends the SOL payment and provides the transaction signature
• Agent calls provenonce_purchase_sigil again with the payment_tx to complete the purchase
• Agent calls provenonce_heartbeat (same payment flow) to prove liveness
• Agent calls provenonce_get_passport to receive a cryptographically signed identity document
• Passport can be verified offline by any third party using the Provenonce authority public key

Agent Flow

Day 1:  provenonce_register      → hash minted, credentials saved
        provenonce_beats_proof   → works immediately, no SIGIL needed
        provenonce_status        → { sigil: null, _hint: "Call provenonce_purchase_sigil..." }

Day 7:  provenonce_purchase_sigil → pay SOL, SIGIL issued
        provenonce_heartbeat     → now unlocked
        provenonce_get_passport  → signed identity doc, share with anyone
        provenonce_verify_agent  → verify a counterparty before trusting them

Environment Variables

Variable	Description	Default
PROVENONCE_API_KEY	Agent API key (pvn_...)	Read from ~/.provenonce/config.json
PROVENONCE_AGENT_HASH	Agent hash (0x...)	Read from ~/.provenonce/config.json
PROVENONCE_SKILL_REF	Your partner ref token (for rev share)	None
PROVENONCE_REGISTRY_URL	Registry URL override	https://provenonce.io

Framework-Agnostic Usage

import { PROVENONCE_TOOLS } from '@provenonce/mcp/tools';

// OpenAI
const tools = PROVENONCE_TOOLS.map(t => ({ type: 'function', function: t }));

// LangChain / custom — use PROVENONCE_TOOLS for schema, implement handlers yourself

Credential Storage

Credentials are stored in ~/.provenonce/config.json with chmod 600 permissions (Unix).

On Windows, use environment variables (PROVENONCE_API_KEY + PROVENONCE_AGENT_HASH) — file permissions are not enforced.

Privacy Policy

Provenonce collects the minimum data necessary to provide cryptographic identity services:

• Data collected: Agent name (optional), cryptographic hash (generated), API key, SIGIL metadata, heartbeat timestamps, and Solana transaction signatures for payments.
• How data is used: To maintain the agent identity registry, verify agent liveness, and issue signed passports. No data is sold to third parties.
• Storage: Agent state is stored in Supabase (PostgreSQL). Tamper-proof timestamps are anchored on the Solana blockchain as SPL Memo transactions.
• Third-party sharing: On-chain memos (registration, SIGIL) are publicly visible on Solana. No other data is shared with third parties.
• Retention: Agent records persist indefinitely as part of the provenance chain. Revoked agents are marked but not deleted.
• Contact: [e-mail]

Full privacy policy: provenonce.dev/legal/privacy

Support

• Documentation: provenonce.dev
• Issues: github.com/jarekpiot/provenonce-mcp/issues
• Email: [e-mail]

What's Coming

• provenonce_kyc — KYC / identity class upgrade
• Auto-heartbeat timer (opt-in)
• Python SDK (provenonce-py)

License

MIT — see LICENSE

Links

• Registry: provenonce.io
• Docs: provenonce.dev
• API: provenonce.io/openapi.yaml