vm-mcp/packages/vaultmesh_mcp/README.md

VaultMesh MCP Server

Model Context Protocol server exposing VaultMesh Guardian and Treasury tools to Claude.

Installation

pip install -r packages/vaultmesh_mcp/requirements.txt

Tools Exposed

Guardian Tools

Tool	Description	Capability
guardian_anchor_now	Anchor scrolls and compute Merkle root snapshot	anchor
guardian_verify_receipt	Verify a receipt exists by hash	guardian_view
guardian_status	Get status of all scrolls	guardian_view

Treasury Tools

Tool	Description	Capability
treasury_create_budget	Create a new budget	treasury_write
treasury_balance	Get budget balance(s)	treasury_view
treasury_debit	Spend from a budget	treasury_write
treasury_credit	Add funds to a budget	treasury_write

Usage

With Claude Desktop

Add to your Claude Desktop config (~/.config/claude-desktop/config.json):

{
  "mcpServers": {
    "vaultmesh": {
      "command": "python",
      "args": ["-m", "packages.vaultmesh_mcp.server"],
      "cwd": "/path/to/vaultmesh",
      "env": {
        "VAULTMESH_ROOT": "/path/to/vaultmesh"
      }
    }
  }
}

Standalone Testing

# List available tools
python -m packages.vaultmesh_mcp.server

# Call a tool directly
python -m packages.vaultmesh_mcp.server guardian_status '{}'

# Create a budget
python -m packages.vaultmesh_mcp.server treasury_create_budget '{"budget_id": "ops-2025", "name": "Operations", "allocated": 100000}'

# Anchor all scrolls
python -m packages.vaultmesh_mcp.server guardian_anchor_now '{}'

Receipt Emission

Every tool call emits a receipt to receipts/mcp/mcp_calls.jsonl containing:

{
  "schema_version": "2.0.0",
  "type": "mcp_tool_call",
  "timestamp": "2025-12-07T12:00:00Z",
  "scroll": "mcp",
  "tags": ["mcp", "tool-call", "<tool_name>"],
  "root_hash": "blake3:...",
  "body": {
    "tool": "<tool_name>",
    "arguments": {...},
    "result_hash": "blake3:...",
    "caller": "did:vm:mcp:client",
    "success": true
  }
}