{
  "markdown": "# PiQrypt MCP Server\n<!-- mcp-name: io.github.PiQrypt/audit-trail -->\n\n**Cryptographic Audit Trail for AI Agents via Model Context Protocol**\n\n[![MCP](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io)\n[![npm downloads](https://img.shields.io/npm/dt/%40piqrypt%2Fmcp-server?style=flat-square&color=00e09a)](https://www.npmjs.com/package/@piqrypt/mcp-server)\n[![AISS](https://img.shields.io/badge/AISS-v2.0-green)](https://aiss-standard.org)\n[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n[![Python](https://img.shields.io/badge/python-3.8+-blue)](https://python.org)\n[![Node](https://img.shields.io/badge/node-18+-green)](https://nodejs.org)\n[![Add to Cursor](https://img.shields.io/badge/Cursor-Install%20MCP-blue)](cursor://anysphere.cursor-deeplink/mcp/install?name=piqrypt&config=eyJjb21tYW5kIjoicGlxcnlwdC1tY3Atc2VydmVyIiwiYXJncyI6W119)\n[![Install in Claude](https://img.shields.io/badge/Claude-Install%20MCP-blue)](https://claude.ai/settings/integrations)\n---\n\n## 🚀 What is PiQrypt MCP?\n\nPiQrypt MCP Server provides **Model Context Protocol** access to [PiQrypt](https://github.com/piqrypt/piqrypt) — the post-quantum cryptographic audit trail for AI agents.\n\n**Use cases:**\n- 🤖 **AI Agents**: Sign every decision with cryptographic proof\n- 📊 **n8n Workflows**: Add audit trail to automation workflows\n- 🏦 **Trading Bots**: SEC/FINRA compliance for automated trading\n- 👥 **HR Automation**: GDPR-compliant AI hiring decisions\n- 🏥 **Healthcare AI**: HIPAA audit trail for medical decisions\n\n---\n\n## 📦 Installation\n\n### Prerequisites\n\n**1. Install piqrypt (required — Python 3.8+)**\n\n```bash\npip install piqrypt\n```\n\nThe MCP server delegates all cryptographic operations to the `piqrypt` Python package.\nIf it is not installed, the server will return a clear error on every tool call.\n\n**2. Install the MCP server (Node.js 18+)**\n\n```bash\nnpm install -g @piqrypt/mcp-server\n```\n\n### Install via npx (no global install)\n\n```bash\nnpx @piqrypt/mcp-server\n```\n\n### Build from source\n\n```bash\ngit clone https://github.com/piqrypt/piqrypt-mcp-server\ncd piqrypt-mcp-server\nnpm install\nnpm run build\n```\n\n### PIQRYPT_PYTHON — custom Python environment\n\nBy default the server uses `python3` (Linux/Mac) or `python` (Windows).\nIf `piqrypt` is installed in a virtual environment, set this variable to point to the right interpreter:\n\n**Windows**\n```cmd\nset PIQRYPT_PYTHON=C:\\path\\to\\venv\\Scripts\\python.exe\n```\n\n**Linux / Mac**\n```bash\nexport PIQRYPT_PYTHON=/path/to/venv/bin/python\n```\n\nTo make it persistent, add it to your MCP client configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"piqrypt\": {\n      \"command\": \"piqrypt-mcp-server\",\n      \"args\": [],\n      \"env\": {\n        \"PIQRYPT_PYTHON\": \"/path/to/venv/bin/python\"\n      }\n    }\n  }\n}\n```\n\n---\n\n## ⚙️ Configuration\n\n### Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"piqrypt\": {\n      \"command\": \"piqrypt-mcp-server\",\n      \"args\": []\n    }\n  }\n}\n```\n\n### n8n (v1.88+)\n\n1. Install n8n MCP integration\n2. Add PiQrypt MCP server to configuration\n3. Use in workflows via MCP node\n\n---\n\n## Compatible with\n\n### MCP clients\n| Client | Version | Notes |\n|--------|---------|-------|\n| Any MCP-compatible client | MCP spec 2024-11+ | stdio transport |\n| n8n | 1.88+ | via MCP node |\n| Cursor | any | add to mcp settings |\n| VS Code | any | add to mcp settings |\n| Continue | any | add to mcp settings |\n| Windsurf | any | add to mcp settings |\n\n### Automation platforms (via MCP node)\n| Platform | Integration | Use case |\n|----------|-------------|----------|\n| n8n | MCP node (native) | No-code audit trail |\n| Make.com | HTTP module | Webhook-triggered stamping |\n| Zapier | Webhooks + HTTP | Basic event recording |\n\n### What you can audit with PiQrypt MCP\n\nEvery tool call goes through the same 4 operations —\nstamp, verify, export, search. Here is what that means\nin practice depending on your context:\n\n**Automated trading / finance**\nAny agent that submits orders, rebalances portfolios,\nor triggers transactions can stamp each decision before\nexecution. The signed chain is exportable for SEC/FINRA\naudit without any additional infrastructure.\n\n**HR and hiring automation**\nAny workflow that evaluates candidates, scores CVs,\nor routes applicants can stamp each decision. Provides\na GDPR Art.22 compliant audit trail for AI-assisted\nhiring — who decided what, when, and what data was used\n(hashed, never stored raw).\n\n**Content and publishing pipelines**\nAny agent that drafts, approves, or publishes content\ncan stamp each step. Useful when multiple AI agents\ncollaborate and you need to prove attribution —\nwhich agent wrote what, in what order.\n\n**DevOps and CI/CD**\nAny agent that triggers deployments, merges branches,\nor rotates secrets can stamp each action. Provides a\ntamper-evident record of infrastructure changes made\nby autonomous agents.\n\n**Healthcare and medical AI**\nAny diagnostic or triage agent can stamp each\nrecommendation. Provides a HIPAA-compliant audit trail\nlinking each AI output to a verifiable agent identity.\n\n**The common pattern in all cases:**\n```\n[Agent makes decision]\n↓\npiqrypt_stamp_event    ← sign + chain\n↓\n[Agent executes action]\n↓\npiqrypt_export_audit   ← portable proof, verifiable\n                          without PiQrypt installed\n```\n\n---\n\n## 🛠️ Available Tools\n\n### 1. `piqrypt_stamp_event`\n\nSign an AI decision with cryptographic proof.\n\n**Parameters:**\n- `agent_id` (string, required): Agent identifier\n- `payload` (object, required): Decision data\n- `previous_hash` (string, optional): Previous event hash for chaining\n\n**Example:**\n```typescript\nconst event = await mcp.call('piqrypt_stamp_event', {\n  agent_id: 'trading_bot_v1',\n  payload: {\n    action: 'buy',\n    symbol: 'AAPL',\n    quantity: 100,\n    price: 150.25\n  }\n});\n```\n\n**Returns:**\n```json\n{\n  \"version\": \"AISS-1.0\",\n  \"agent_id\": \"trading_bot_v1\",\n  \"timestamp\": 1739382400,\n  \"nonce\": \"uuid-...\",\n  \"payload\": { ... },\n  \"previous_hash\": \"sha256:...\",\n  \"signature\": \"base64:...\"\n}\n```\n\n---\n\n### 2. `piqrypt_verify_chain`\n\nVerify integrity of event chain.\n\n**Parameters:**\n- `events` (array, required): Events to verify\n\n**Example:**\n```typescript\nconst result = await mcp.call('piqrypt_verify_chain', {\n  events: [event1, event2, event3]\n});\n```\n\n**Returns:**\n```json\n{\n  \"valid\": true,\n  \"events_count\": 3,\n  \"chain_hash\": \"sha256:...\",\n  \"errors\": []\n}\n```\n\n---\n\n### 3. `piqrypt_export_audit`\n\nExport audit trail for compliance.\n\n**Parameters:**\n- `agent_id` (string, required): Agent to export\n- `certified` (boolean): Request PiQrypt certification\n- `output_format` (string): `json` or `pqz`\n\n**Example:**\n```typescript\nconst audit = await mcp.call('piqrypt_export_audit', {\n  agent_id: 'trading_bot_v1',\n  certified: true,\n  output_format: 'json'\n});\n```\n\n---\n\n### 4. `piqrypt_search_events`\n\nFast search via SQLite index.\n\n**Parameters:**\n- `event_type` (string, optional): Filter by type\n- `from_timestamp` (number, optional): Start time\n- `to_timestamp` (number, optional): End time\n- `limit` (number): Max results (default: 100)\n\n**Example:**\n```typescript\nconst trades = await mcp.call('piqrypt_search_events', {\n  event_type: 'trade_executed',\n  from_timestamp: 1739300000,\n  limit: 50\n});\n```\n\n---\n\n## 📊 Vigil Dashboard (optional, free)\n\nEvery stamped event is visible in Vigil —\nPiQrypt's local monitoring dashboard.\n\n> **Note:** Vigil is not launched automatically by the MCP server.\n> You must start it separately before opening the dashboard.\n\n```bash\npiqrypt vigil\n# → http://localhost:8421\n```\n\nFree tier includes: chain health, VRS risk score,\n7-day history, CRITICAL alerts.\n[Upgrade to Pro](https://piqrypt.com) for 90-day\nhistory, TrustGate governance, and post-quantum\nsignatures.\n\n---\n\n## 🗑️ Managing Agents\n\nAgents are created automatically on first stamp. To view and delete agents:\n\n1. Start Vigil: `piqrypt vigil`\n2. Open http://localhost:8421\n3. Go to **All Agents** view\n4. Check the agents to delete → click **✕ Delete selected**\n5. Confirm — Vigil returns to the welcome screen when no agents remain\n\n> Agents are stored in `~/.piqrypt/agents/` on your machine.\n> Deleting an agent removes its keys and event history permanently.\n\n---\n\n## 🔒 Security Model\n\n### Process Isolation\n\n```\n┌─────────────────────────────────────┐\n│  MCP Client (any MCP-compatible client)     │\n│  ↓ JSON-RPC over stdio              │\n├─────────────────────────────────────┤\n│  MCP Server (TypeScript/Node.js)    │  ← No crypto here\n│  ↓ subprocess call                  │\n├─────────────────────────────────────┤\n│  Python Bridge (bridge.py)          │\n│  ↓ invokes CLI                      │\n├─────────────────────────────────────┤\n│  PiQrypt CLI (Python)               │\n│  ↓ uses                             │\n├─────────────────────────────────────┤\n│  Core Crypto (aiss package)         │  ← All crypto here\n│  • Ed25519 / Dilithium3             │\n│  • RFC 8785 canonical JSON          │\n│  • Hash chains                      │\n└─────────────────────────────────────┘\n```\n\n### Guarantees\n\n✅ **Private keys never exposed** to MCP layer  \n✅ **All crypto in Python** (Ed25519, Dilithium3)  \n✅ **Same security as CLI** (process isolation)  \n✅ **RFC AISS-1.1 compliant** (identical output)  \n✅ **Input validation** before subprocess call\n\n---\n\n## 📚 Examples\n\n### Trading Bot (n8n)\n\n```\n[Webhook: price alert] \n    ↓\n[AI Decision: buy/sell?]\n    ↓\n[PiQrypt MCP: stamp decision]  ← Audit trail\n    ↓\n[Execute trade API]\n    ↓\n[Database: store proof]\n```\n\n### HR Automation\n\n```\n[Upload CV]\n    ↓\n[AI Agent: evaluate candidate]\n    ↓\n[PiQrypt MCP: stamp evaluation]  ← GDPR compliance\n    ↓\n[Email HR team]\n```\n\n---\n\n## 🧪 Testing\n\n```bash\n# Build\nnpm run build\n\n# Test bridge\npython3 src/python/bridge.py stamp '{\"agent_id\":\"test\",\"payload\":{\"action\":\"test\"}}'\n\n# Test MCP server (manual)\nnode dist/index.js\n# Then send MCP request via stdin\n```\n\n---\n\n## 🔧 Troubleshooting\n\n### `Error: piqrypt is not installed in this Python environment`\n\nThe Python interpreter used by the MCP server cannot find the `piqrypt` package.\n\n**Fix:**\n```bash\npip install piqrypt\n```\n\nIf `piqrypt` is installed in a virtual environment and not the system Python, set `PIQRYPT_PYTHON` to point to the correct interpreter:\n\n```bash\n# Linux / Mac\nexport PIQRYPT_PYTHON=/path/to/venv/bin/python\n\n# Windows\nset PIQRYPT_PYTHON=C:\\path\\to\\venv\\Scripts\\python.exe\n```\n\nTo verify which Python the server will use:\n```bash\n# Linux / Mac\n$PIQRYPT_PYTHON -c \"import aiss; print('ok')\"\n\n# Windows\n%PIQRYPT_PYTHON% -c \"import aiss; print('ok')\"\n```\n\n---\n\n## 📖 Documentation\n\n- [MCP Setup Guide](docs/mcp-setup.md)\n- [Tools Reference](docs/tools-reference.md)\n- [n8n Integration](docs/n8n-integration.md)\n- [Security Model](docs/security-model.md)\n- [RFC Compliance](docs/rfc-compliance.md)\n\n---\n\n## 🤝 Contributing\n\nWe welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md).\n\n---\n\n## 📄 License\n\nMCP Server → MIT License - see [LICENSE](LICENSE)\nPiQrypt Core → free tier + commercial tiers\n\n---\n\n## 🔗 Links\n\n- **PiQrypt Core**: https://github.com/piqrypt/piqrypt\n- **MCP Protocol**: https://modelcontextprotocol.io\n- **n8n**: https://n8n.io\n- **Documentation**: https://docs.piqrypt.com\n\n---\n\n**Built with ❤️ by PiQrypt Inc.**\n",
  "bytes": 11322,
  "sha": "27d96265bed4714df20b0b2b5918ab39b63ed3ecc268c7c750137da0ebf353fe",
  "repo_slug": "piqrypt/piqrypt-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_piqrypt_audit_trail_5cbc013c/readme"
}